Music Component Functions: Synthesizer19

The functions in this section obtain specific information about a synthesizer and obtain a best instrument fit for a requested tone from the available instruments within the synthesizer; play a note with a specified pitch, volume, and duration; get and set a particular synthesizer knob; obtain synthesizer knob information; and get and set external MIDI procedure name entry points.

MusicGetDescription

The MusicGetDescription function returns a structure describing the synthesizer controlled by the music component device.



 
pascal ComponentResult MusicGetDescription( 

                     MusicComponent mc, 

                     SynthesizerDescription *sd);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
*sd: Pointer to synthesizer description structure Synthesizer Description Structure .
function result: A result code.

DISCUSSION

The MusicGetDescription function returns a structure describing the specified music component device. The SynthesizerDescription record is filled out by the particular music component.

MusicFindTone

The MusicFindTone function returns an instrument number based on a tone description.



 
pascal ComponentResult MusicFindTone(

                     MusicComponent mc, 

                     ToneDescription *td,

                     long *libraryIndexOut, 

                     unsigned long *fit);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
*td: Pointer to a tone description structure Tone Description Structure .
*libraryIndexOut: On exit, contains the number of the best-matching instrument. Only General MIDI numbers are guaranteed to be the same for later instantiations of the component.
*fit: On exit, indicates how well an instrument matches the tone description. For valid values, see "Tone Fit Flags" .
function result: A result code.

DISCUSSION

The MusicFindTone function returns the number of the best-matching instrument provided by the specified music component. The closeness of the match is specified by the fit parameter.

The music component searches for an instrument as follows:

If the synthesizerType field of the td parameter matches the type of the specified music component, it first tries to find an instrument that matches the value of the instrumentNumber field of the td parameter. If this value is in the range 129-16512 , which specifies a GS instrument, and the GS instrument is not available, it tries to find the General MIDI instrument that corresponds to it, which has the number ((GSinstrumentnumber - 1) & 0x7F) + 1)) . If the value is greater than 16512 , which specifies a transient ROM instrument or internal instrument index value, it tries to find an instrument that matches the synthesizerName field of the td parameter. If that fails, it tries to find an instrument that matches the value of the value of the gmNumber field of the td parameter.
If the synthesizerType field of the td parameter does not match the type of the specified music component, it tries to find an instrument that matches the value of the gmNumber field of the td parameter.

If none of these rules apply, or the fields are "blank" (zero for the type or numeric fields, or zero-length for the strings), then the call returns instrument 1 and a fit value of zero. The synthesizerName field may be ignored by the component; it is used by the note allocator when deciding which music device to use.

MusicPlayNote

The MusicPlayNote function plays a note on a specified part at a specified pitch and velocity.



 
pascal ComponentResult MusicPlayNote(

                     MusicComponent mc, 

                     long part, 

                     long pitch, 

                     long velocity);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The part to play the note on.
pitch: The pitch at which to play the note. Values are 0-127 for MIDI pitch or greater than 65535 for microtonal values.
velocity: How hard to strike the key. Values are 0-127 where 0 is silence.
function result: A result code.

DISCUSSION

The MusicPlayNote function is used to play notes by their pitch. If the pitch is specified by a number from 0 to 127, it is a MIDI pitch, where 60 is middle-C. If the pitch is a positive number above 65535, the value is a fixed-point pitch value. Thus, microtonal values may be specified.

Velocity refers to how hard the key is struck (if performed on a keyboard-instrument); typically, this translates directly to volume, but on many synthesizers this also subtly alters the timbre of the tone.

The current note continues to play until a MusicPlayNote with the same pitch and velocity of 0 turns the note off.

MusicGetKnob

The MusicGetKnob function returns the value of the specified global synthesizer knob. A global knob controls an aspect of the entire synthesizer. It is not specific to a part within the synthesizer.



 
pascal ComponentResult MusicGetKnob(

                     MusicComponent mc,

                     long knobID);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobID: Knob index or ID.
function result: A result code.

MusicSetKnob

The MusicSetKnob function modifies the value of the specified global synthesizer knob. A global knob controls an aspect of the entire synthesizer. It is not limited to a part within the synthesizer.



 
pascal ComponentResult MusicSetKnob(

                     MusicComponent mc,

                     long knobID, 

                     long knobValue);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobID: Knob index or ID.
knobValue: Value for specified knob.
function result: A result code.

MusicGetKnobDescription

The MusicGetKnobDescription function returns a pointer to an initialized knob description structure describing a global synthesizer knob. A global knob controls an aspect of the entire synthesizer; it is not limited to a part within the synthesizer.



 
 pascal ComponentResult MusicGetKnobDescription(

                     MusicComponent mc,

                     long knobIndex, 

                     KnobDescription *mkd);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobIndex: Knob index or ID.
*mkd: Pointer to a knob description structure Knob Description Record .
function result: A result code.

DISCUSSION

The initialized KnobDescription structure provides the application default values associated with the particular knob. You can use the information returned by a call to the MusicGetKnobDescription function to reset a knob to some known, usable value.

MusicGetInstrumentKnobDescription

The MusicGetInstrumentKnobDescription function gets the description of an instrument knob.



 
extern pascal ComponentResult MusicGetInstrumentKnobDescription(

                     MusicComponent mc,

                     long knobIndex,

                     KnobDescription *mkd)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobIndex: A knob index or knob ID.
mkd: On exit, a knob description record Knob Description Record .
function result: A result code.

DISCUSSION

The MusicGetInstrumentKnobDescription function takes a music component instance identifier in the mc parameter and a knob index or knob ID in the knobIndex parameter. It returns a knob description record in the *mkd parameter.

MusicGetDrumKnobDescription

The MusicGetDrumKnobDescription function returns a description of a drum kit knob.



 
extern pascal ComponentResult MusicGetDrumKnobDescription(

                     MusicComponent mc,

                     long knobIndex,

                     KnobDescription *mkd)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobIndex: A knob index or knob ID.
*mkd: A pointer to a knob description record Knob Description Record .
function result: A result code.

DISCUSSION

The MusicGetDrumKnobDescription function takes a music component in the mc parameter and a knob index or knob ID in the knobIndex parameter. It returns a knob description record in the *mkd parameter.

MusicGetKnobSettingStrings

The MusicGetKnobSettingStrings function returns a list of knob setting names known by the specified music component.



 
extern pascal ComponentResult MusicGetKnobSettingStrings(

                     MusicComponent mc,

                     long knobIndex,

                     long isGlobal,

                     Handle *settingsNames,

                     Handle *settingsCategoryLasts,

                     Handle *settingsCategoryNames)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
knobIndex: The knob index or knob ID.
isGlobal: If a knob index is used, indicates whether the specified knob is a global knob.
settingsNames: The requested list of knob setting strings formatted as a short followed by packed strings.
settingsCategoryLasts: A handle containing a group of short integers, the first of which contains the number of shorts to follow.
settingsCategoryNames: Knob setting category names formatted as a short followed by a list of names.
function result: A result code.

All handles must be disposed of by the caller.

MusicSetMIDIProc

The MusicSetMIDIProc function tells the music component what procedure to call when it needs to send MIDI data. This call is implemented only by a music component for a MIDI synthesizer.



 
pascal ComponentResult MusicSetMIDIProc(

                     MusicComponent mc, 

                     MusicMIDISendUPP MIDISendProc, 

                     long refCon);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
MIDISendProc: A pointer to the procedure to use when sending MIDI data.
refcon: Contains a reference constant value. The Movie Toolbox passes this reference constant to your error-notification function each time it calls your function.
function result: A result code.

MusicGetMIDIProc

The MusicGetMIDIProc function returns a pointer to the procedure a music component is using to process external MIDI notes.



 
pascal ComponentResult MusicGetMIDIProc(

                     MusicComponent mc, 

                     MusicMIDISendUPP *MIDISendProc, 

                     long *refCon);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
*MIDISendProc: Pointer to a MIDI serial port call.
*refcon: Contains a reference constant. The Movie Toolbox passes this reference constant to your error-notification function each time it calls your function.
function result: A result code.

DISCUSSION

The MusicGetMIDIProc function returns, in the *MIDISendProc parameter, a pointer to the function that processes external MIDI notes. This function was set by a previous call to the MusicSetMIDIProc function. If no function has been set with the MusicSetMIDIProc function, MusicGetMIDIProc returns zero in the *MIDISendProc parameter.

MusicGetMIDIPorts

The MusicGetMIDIPorts function returns the number of input and output ports a MIDI device has.



 
extern pascal ComponentResult MusicGetMIDIPorts(

                     MusicComponent mc,

                     long *inputPortCount,

                     long *outputPortCount)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
inputPortCount: On exit, the number of input MIDI ports available to the music component.
outputPortCount: On exit, the number of output MIDI ports available to the music component.
function result: A result code.

DISCUSSION

The function takes a music component identifier in the mc parameter and returns, in the inputPortCount and outputPortCount parameters, the number of MIDI input and output ports available to the music component.

This call is implemented only for a hardware synthesizer, such as a NuBus or PCI card device.

MusicSendMIDI

Use the MusicSendMIDI function to send a MIDI packet to a specified port.



 
extern pascal ComponentResult MusicSendMIDI(

                     MusicComponent mc,

                     long portIndex,

                     MusicMIDIPacket *mp)

mc: Music component instance returned by NAGetRegisteredMusicDevice .
portIndex: The index of the port to send the MIDI packet to. The index value is 1 through the port count returned by the MusicGetMIDIPorts function.
mp: The music MIDI packet to be sent.
function result: A result code.

DISCUSSION

The MusicSendMIDI function takes a music component in the mc parameter and a port index in the portIndex parameter. It sends the MIDI music packet specified by the *mp parameter to the specified port.

This call is implemented only for a hardware synthesizer, such as a NuBus or PCI card device.

MusicGetDeviceConnection

You can use the MusicGetDeviceConnection function to find out how many hardware synthesizers are available to a music component and to get the IDs for those devices.



 
extern pascal ComponentResult MusicGetDeviceConnection(

                     MusicComponent mc,

                     long index,

                     long *id1,

                     long *id2)

mc: Music component returned by NAGetRegisteredMusicDevice .
index: Index of the device for which you want to find out the IDs. Set to 0 if you are calling to get the number of hardware devices.
id1: On exit, a hardware synthesizer ID.
id2: On exit, another hardware synthesizer ID.
function result: A result code.

DISCUSSION

To get the number of hardware synthesizers available to the music component specified in the mc parameter and an index you can use to request ID numbers for a specific device, call the MusicGetDeviceConnection function with a value of 0 for the index parameter. You can then pass an index value in the index parameter, and the function returns hardware synthesizer IDs in the *id1 and *id2 parameters.

This call is implemented only for a hardware synthesizer, such as a NuBus or PCI card device.

MusicUseDeviceConnection

The MusicUseDeviceConnection function tells a music component which hardware synthesizer to talk to.



 
extern pascal ComponentResult MusicUseDeviceConnection(

                     MusicComponent mc,

                     long id1,

                     long id2)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
id1: The ID of the device returned in the *id1 parameter of the MusicGetDeviceConnection function.
id2: The ID of the device returned in the *id2 parameter of the MusicGetDeviceConnection function.
function result: A result code.

DISCUSSION

This call is implemented only for a hardware synthesizer, such as a NuBus or PCI card device.